feat(get-state-by-cep): add getStateByCep, the state that owns a CEP range - #562

Update (2026-09-27)

• getMunicipalityByCep was removed from this PR and from its history: the maintainer decided to ship it later, generated from an official Correios export. The community gist its table was generated from (pinned revision of hugosenari/ec1a7d88…) turned out to be out of date: 406 ranges started at -001 instead of -000 (for example getMunicipalityByCep("01000-000") was null for São Paulo), and 135 municipalities differed from the current Correios faixas after the recodings since 2020 (for example 33230-000 read as Vespasiano instead of Lagoa Santa). Its range table, its generator (scripts/municipality-cep-ranges.ts) and the scripts/data.ts step that ran it, the OTHER_NAMES spellings, its docs, CONTRIBUTING notes, JSR entry, API report line and bundle-size rows went with it. What stays: getStateByCep, the shared _internals/find-cep-range lookup, and the rename of the internal IBGE municipality table cities.ts → municipalities.ts.

Stacked on #560. This PR sits on top of #560 (getCnpjInfo) and merges after it, which in turn sits on #559 and #558. Its base branch is claude/get-cnpj-info, so the diff shown here is the getStateByCep changes alone. Part of stack #591.

What

One offline CEP range lookup, plus one naming cleanup:

• getStateByCep: the state (UF) that owns a CEP, from the CEP ranges the Correios assign to each state. A 30 row pure literal in src/get-state-by-cep/constants.ts.
• The validate-parse-find logic lives in a new internal, findCepRange (src/_internals/find-cep-range/find-cep-range.ts), so a later CEP range lookup can reuse it.
• Renamed the internal src/_internals/constants/cities.ts to municipalities.ts: it exports Municipality, not City, and nothing public imports the path directly, so this is not a breaking change. No public export is renamed.

No network call: it answers from a range table, not a CEP API.

API

getStateByCep(value: string | number): State | null

• Accepts what isValidCep accepts: 8 digits, string or number, with spaces, dots and hyphens ignored. A number must be a non-negative integer (isLookupCode), so -20040020 and 2004002.5 are null instead of being read as a CEP. A CEP starting with 0 has to be a string, as in isValidCep.
• Returns the same State object as getStates / getStateByIbgeCode (a fresh copy), so it composes with the rest of the state family.
• null for an invalid CEP, for any non string/number input, and for a CEP outside every range.

getStateByCep("01310-100"); // { code: "SP", name: "São Paulo", regionCode: "SE", regionName: "Sudeste", ibgeCode: 35 }
getStateByCep(20040020)?.code; // "RJ"
getStateByCep("69300-000")?.code; // "RR" (inside the Amazonas block)
getStateByCep("72800-000")?.code; // "GO" (inside the Distrito Federal block)
getStateByCep("78900-000"); // null (no state owns 78900-000 to 78999-999)

Ranges in the getStateByCep table (three states have two):

Sources

• Official: https://buscacepinter.correios.com.br/app/faixa_cep_uf_localidade/index.php (Correios "Busca Faixa de CEP"; a search with only the UF answers the ranges of the state). This search is behind a CAPTCHA, so I could not read its answers from a script and did not try to get around it.
• Based on: https://gist.github.com/tamnil/792a6a66f6df9fc028041587cfca0c3d, a copy of the answers of that search (UF, city, first CEP, last CEP). The 30 rows with an empty city are the state ranges used here.
• Official cross-check: https://www.correios.com.br/acesso-a-informacao/licitacoes-e-contratos/credenciamento-ponto-de-coleta/arquivos/localidades (Correios, "Anexo 3, Localidades alvo (CEPs ou faixas de CEP)", 76 pages, grouped by UF). The 10,189 CEPs it lists under the 27 UF headings all land in the UF of their heading, except one evident typo in the document (22930-869 printed under Espírito Santo). It confirms, among others, the Goiás municipalities around Brasília at 72800-001 and up, Distrito Federal up to 73405-999, Mato Grosso up to 78899-999 and Rondônia from 76800-001.

The 30 getStateByCep boundaries are cross-verified

They do not rest on the tamnil gist alone. Every boundary was re-derived from sources independent of it, and all 30 match the table:

• The official "Localidades alvo" PDF above, re-extracted independently: same 10,189 CEPs, same single typo, no contradiction. It pins most boundaries tightly (for example DF 72774-999 against GO 72800-001, GO 72979-999 against DF 73000-001, MT 78899-999).
• The hugosenari community CSV of per-municipality Correios CEP ranges (https://gist.github.com/hugosenari/ec1a7d88f5bdd01844424dbc9aff9590, 5,764 rows): mapping both endpoints of every row through this 30 row UF table gives 0 mismatches over 11,528 endpoints, and the CSV pins each of the 30 boundaries to the adjacent CEP the same way the PDF does (for example PA 68899-999 against AP 68900-001). It is out of date at the municipality level (see the Update above), but its state boundaries agree with every other source.
• Live ViaCEP lookups (a DNE mirror) on the boundaries the PDF leaves loose: 69399-000 Cantá/RR and 69400-970 Manacapuru/AM, 76801-000 Porto Velho/RO, 73700-000 Padre Bernardo/GO, 72800-010 Luziânia/GO, 68890-000 Afuá/PA, 68900-010 Macapá/AP, 79002-000 Campo Grande/MS.
• Five further independent range tables agree on all 30 rows: JoseQuintas/sefazclass (json/sefazcepuf.json), klawdyo/validation-br (src/cep.ts), pdrodavi/cep2uf, and the carrier and e-commerce tables of bring.com.br, blog.shoppub.com.br and ajuda.lojaintegrada.com.br.
• The table has no overlap and exactly the two gaps it documents (00000-000 to 00999-999 and 78900-000 to 78999-999).

Two secondary sources disagree, and both are wrong:

• MT ends at 78899-999, not 78999-999. The Wikipedia zone table lists "MT Interior | 78110 - 78999", which would close the 789xx gap. The official PDF's highest MT CEP is 78899-999 (Sorriso) and it lists no CEP at all in 789xx; the hugosenari CSV has none of its municipality ranges there either; live ViaCEP answers {"erro":true} for 78900-000, 78950-000 and 78999-000. 789xx is the range Rondônia vacated when it was moved to 768xx, which is the same move that took Goiás down to 76799-999. The gap stays.
• SP is one range, not two. datasets-br/state-codes records SP as 01000-000–09999-999 plus 11000-000–19999-999. The Correios UF faixa, which is what this table copies, gives SP a single 01000-000–19999-999, and so does every other source checked. getStateByCep("10000-000") therefore answers SP although no city uses 10xxx: the São Paulo capital ranges skip over 10xxx, the "Localidades alvo" PDF has no CEP starting with 10 anywhere in its 76 pages, and live ViaCEP answers {"erro":true} for 10000-000. A faixa is the block the state owns, not a guarantee that every CEP in it is in use, and SP has other unused blocks. The JSDoc and both docs say so.

Naming: the internal municipality table

Looked at git log, the JSDoc of getCities/getMunicipality and CONTRIBUTING.md; there is no mention of a planned rename of any public export. Commit d313bcc2 (docs(municipalities): deprecate getCities and getMunicipality in favour of the municipality family) already settled the public naming on main:

The municipality is the entity of the Constituição (art. 18) and of the IBGE dataset the library ships, so getMunicipalities and getMunicipalityByCode are the API. getCities (names only) and the asynchronous getMunicipality of 2.3.0 keep working unchanged and are marked deprecated, to be removed in the next major; matching a municipality by name, which getMunicipality also did, is left to the application over getMunicipalities, since names vary in ways no library rule settles (abbreviations, former names, hyphens, typos).

So no public export is renamed in this PR (that would be the exact breaking change the release must avoid). What did move: the internal _internals/constants/cities.ts to municipalities.ts, since it exports Municipality, is behind getMunicipalities/getMunicipalityByCode/getMunicipality/getCities alike, and nothing public imports its path. The generated file is unchanged apart from its path; scripts/cities.ts, scripts/data.ts and scripts/data-summary.ts point at the new path.

Verification

• npm run check: pass
• npm run test -- --run: pass
• npm run test:coverage: 100% statements, branches, functions and lines
• npm run build, npm run check:api:update: pass, report committed (one new export: getStateByCep; Municipality re-exported from its new path)
• npm run check:unused: pass
• npm run check:duplication: 0 clones
• npm run check:tree-shaking: getStateByCep 4620 B / 1565 B gzip
• npm run check:commits: pass
• npm run test:mutation -- --mutate 'src/_internals/find-cep-range/find-cep-range.ts': 100% (17 killed, 0 survived)
• npm run test:mutation -- --mutate 'src/get-state-by-cep/get-state-by-cep.ts': 100% (9 killed, 0 survived)
• bun test src and npm run test:deno: pass
• npm run build:docs and npm run build:jsr: run, output committed (jsr.json gains ./get-state-by-cep)
• Browser test scripts and the full Stryker run were not run locally; CI runs both.

Open points

• The getStateByCep ranges were not read from the official Correios search itself, because it is behind a CAPTCHA that I did not try to bypass. They come from third party copies of that search, corroborated as described above.
• The table is hand written in src/get-state-by-cep/constants.ts, with no generator under scripts/, because the only official source cannot be fetched by a script.
• Pará is a single range today (66000-000 to 68899-999); the task mentioned it as historically split, and no source checked lists more than one range for it.
• isValidCep reads -20040020 and 2004002.5 as valid CEPs today; getStateByCep rejects them as numbers (they stay accepted as strings such as "20040-020"). That util was left untouched.

Rebase onto #560

Rebased from main onto claude/get-cnpj-info, so this branch now carries #558, #559 and #560 underneath it. Conflicts resolved:

• docs/llms.txt and docs/llms-full.txt are no longer tracked (they are generated now), so both were git rm-ed.
• The getStateByCep section of docs/utilities.md and docs/pt-br/utilities.md was ported into the new per-utility format of feat: Standard Schema wrapper, JSR, pkg.pr.new, docs previews and a playground #556: a short paragraph, a bullet list for the accepted input and the edge cases, the javascript block, and a Source: line pointing at the Correios "Busca Faixa de CEP".
• src/index.ts and src/index.test.ts kept strictly alphabetical, between getPixPayloadInfo and getStateByIbgeCode.
• jsr.json (new on main) regenerated with npm run build:jsr, and reports/api/brazilian-utils.api.md with npm run check:api:update. Both are folded into the commits that own them, with no separate "regenerate" commit.

Re-verified on the rebased branch: npm run check, npm run test:coverage (100% statements, branches, functions and lines), npm run build, npm run check:unused, npm run check:duplication and npm run check:commits all pass.

Summary by CodeRabbit

• New Features

  • Added offline CEP lookups for Brazilian states and municipalities.
  • Supports formatted CEP strings and non-negative integer inputs, including punctuation.
  • Returns matching state or municipality details for recognized CEP ranges, and null for invalid, uncovered, or unsupported ranges.
  • Added both functions to the public package API.

• Documentation

  • Added usage details and API references in English and Portuguese documentation.
  • Updated municipality terminology and bundle-size information.